home *** CD-ROM | disk | FTP | other *** search
/ CD ROM Paradise Collection 4 / CD ROM Paradise Collection 4 1995 Nov.iso / filutil / pagin501.zip / PAGINATE.TXT < prev   
Text File  |  1995-01-09  |  61KB  |  1,497 lines
  1. # % PAGINATE.TXT -- documentation for the PAGINATE command
  2. # % Please reformat using "PAGINATE PAGINATE.TXT PAGINATE.DOC /OVERWRITE /-I"
  3. # % (There's a batch file--PAGDOCS.BAT--that does this for you)
  4. # page=60
  5. # adjust
  6. # title
  7. PAGINATE.DOC                          ^B                       Revised: ^A
  8.  
  9. # end
  10. # justify length 80
  11. # index "END" "(See FOOTER)" DUMMY
  12. # index "END" "(See HEADER)" DUMMY
  13. # index "END" "(See MULTICOLUMN)" DUMMY
  14. # index "END" "(See TITLE)" DUMMY
  15. # index "END" "(See UNIT)" DUMMY
  16. # index "Error messages" "(See also /DEBUG parameter)" DUMMY
  17. # index "Environmental variable" "(See SET PAGINATE)" DUMMY
  18. # index "PAGINATE.INI" "(See INI File)" DUMMY
  19. # index "Printer" "(See RESET=string)" DUMMY
  20. # index "Printer" "(See SETUP=string)" DUMMY
  21. # index "INDEX" "(See INCLUDE INDEX)" DUMMY
  22. # index "Length" "Of line" "(See LENGTH command)" DUMMY
  23. # index "Length" "Of page" "(See PAGE command)" DUMMY
  24. # index "Missing data values" "(see INMISS=val)" DUMMY
  25. # index "Missing data values" "(see INMISSC=val)" DUMMY
  26. # index "Missing data values" "(see OUTMISS=val)" DUMMY
  27. # index "Missing data values" "(see OUTMISSC=val)" DUMMY
  28. # index "Sorting" "Case-insensitive" "(See SORTI=varspec)" DUMMY
  29. # index "Sorting" "Descending" "(See SORTD=varspec)" DUMMY
  30. # index "SPACING=1" "(see also SINGLE)" DUMMY
  31. # index "SPACING=2" "(see also DOUBLE)" DUMMY
  32. # index "SPACING=3" "(see also TRIPLE)" DUMMY
  33. # index "Widow lines" "(see ADJUST)" DUMMY
  34. # index "Overview"
  35. The PAGINATE.EXE program formats text files containing embedded "marker"
  36. commands.  Specifically, the program can be used to:
  37.  
  38. # unit
  39. # indent 4-2
  40.   * Align, justify, center text
  41.   * Add headers and footers to pages
  42.   * Add page breaks
  43.   * Control indentation
  44.   * Control spacing
  45.   * Sort the file (alphabetically, not numerically all that well) in either
  46. ascending or descending order.
  47.   * Generate indexes
  48.   * Select fields to print
  49.   * Print out dBase and ASCII-delimited files in tabular forms
  50.   * Bring ASCII-delimited and dBase files into existing text
  51. # end
  52.  
  53. # index "National Institutes of Health"
  54. The PAGINATE.EXE program is based on a document-formatting language that exists
  55. on the mainframe computers at the National Institutes of Health in Bethesda, MD.
  56. The text editor used there is called WYLBUR and it does all sorts of wonderful
  57. things like creating programs.
  58.  
  59. For documentation, you use the WYLBUR text editor and insert document formatting
  60. codes.  These codes determine things like margins, indentation, justification,
  61. spacing, etc.  After you embed all of these formatting commands, you issue a
  62. PAGINATE command and everything's reformatted for you.
  63.  
  64. PAGINATE includes many of the WYLBUR pagination commands and then adds a number
  65. or database operations.   See the notes at the end for how PAGINATE.EXE differs
  66. from my other MULTICOL.EXE program.
  67.  
  68. Typically, I do most of my text formatting using the PE2 text editor which
  69. I dearly love.  The main drags about using PE2 for text formatting are that:
  70.  
  71. # unit
  72. # indent 4-2
  73.   * It doesn't do titles and footers
  74.   * It adds a space after every period followed by a space so "12 p.m. at the
  75. store" comes out as "12 p.m.  at the store"
  76.   * It doesn't handle the database functions (multicolumn printing, dBase,
  77. ASCII-delimited, and sorting) that I plan to add to PAGINATE.
  78.   * It isn't sold anymore and I always hated PE3 after becoming an unwitting
  79. beta tester for them.  (Sorry guys but the free pen you gave me just didn't make up for the
  80. fact that it still didn't work right and I don't like paying to become a beta
  81. tester.)
  82. # end
  83.  
  84.  
  85. #
  86. # index "Marker commands"
  87. Marker commands:
  88.  
  89. PAGINATE typically expects document formatting codes to be embedded in the text
  90. document itself.  If you want the same formating to be used through the entire
  91. document, however, you can pass in most of the arguments (see the "Syntax"
  92. discussion below) or use a separate control file instead.
  93.  
  94. The formatting codes are preceded by a "marker" character.  This is a character
  95. which begins in column 1 of the text (or control) file and is typically the
  96. character "#".  (When passing in the formatting codes, all codes are preceded by
  97. a "/".)
  98.  
  99. For example, you might have text like this:
  100.  
  101. # unit
  102. # verbatim
  103.         #align length 20
  104.         This is some sample text which you have asked to align.  The margins
  105.         will be placed at 1 and 20.  You can use an indent command to shift
  106.         the left margin if desired.
  107. # end
  108.  
  109.  
  110. This example shows one marker statement ("#align length 20") which contains two
  111. formatting commands:  "align" and "length 20".  Formatting commands are keyword
  112. specific.
  113.  
  114. You can put in commands on the same line which have no logical bearing to one
  115. another like "#align spacing=2".  Exceptions:
  116.  
  117.    * Do not do this for INCLUDE statements
  118.    * Do not do this for INDEX statement
  119.  
  120. # index "Semi-colons"
  121. Formatting commands can be separated by semi-colons for clarity but only a space
  122. is required.  The case of the marker statement is irrelevant.
  123.  
  124. After the PAGINATE command is run, the above text will come out like this:
  125.  
  126. # unit
  127. # verbatim
  128.         This is some sample
  129.         text which you have
  130.         asked to align.  The
  131.         margins will be
  132.         placed at 1 and 20.
  133.         You can use an
  134.         indent command to
  135.         shift the left
  136.         margin if desired.
  137. # end
  138.  
  139.  
  140. # index "Paragraphs"
  141. In terms of alignment, justification, variable indentation, etc, the system
  142. treats each paragraph as a separate entity.  A paragraph is defined as beginning
  143. with a blank line or a space.  For example:
  144.  
  145. # unit
  146. # verbatim
  147.         #justify length 25
  148.         This is one paragraph
  149.  
  150.         And this is another paragraph.
  151.         But this is the same paragraph.
  152.           New paragraph here.
  153. # end
  154.  
  155. Comes out as this:
  156.  
  157. # unit
  158. # verbatim
  159.         This is one paragraph
  160.  
  161.         And   this   is   another
  162.         paragraph.  But  this  is
  163.         the same paragraph.
  164.           New paragraph here.
  165. # end
  166.  
  167. # index "Range of formatting"
  168. Formatting commands cover a variety of functions.  Note that formatting within
  169. titles, footers, headers, and UNIT...END blocks does not affect formatting
  170. beyond the END statement.  For example, the length of the title below does not
  171. affect the length outside the title:
  172.  
  173. # unit
  174. # verbatim
  175.         # align length 50
  176.         This text is aligned length 50.  Here comes a title.
  177.         # title center length 70
  178.         This title is centered within length 70.
  179.  
  180.         # end
  181.         This text (outside the TITLE ... END block) is still being
  182.         aligned (not centered) to length 50 (not 70).
  183. # end
  184.  
  185. # index "Short lines"
  186. # index "Paragraphs" "One liners"
  187. Note that JUSTIFY and ALIGN do not affect lines which are on their own and do
  188. not continue to a second line and do not exceed the given page length.
  189.  
  190. As an example, note that the file names shown in the next section ("Sample
  191. files:") are not affected even though they are actually controlled by a JUSTIFY
  192. marker command.  This may seem like an error at times especially if you've
  193. already indented text; remember that indentation is the system's clue that there
  194. is a new paragraph so pre-indented text won't be affected much by the program.
  195.  
  196. This feature is, by the way, frequently useful in defining oddly formatted
  197. sections of text without needing to use a "# UNIT VERBATIM" statement around it;
  198. just make sure each line begins with at least one space and the program won't
  199. touch it.
  200.  
  201.  
  202. # index "Sample files"
  203. Sample files:
  204.  
  205. An example input file and its related components are included in this ZIP
  206. under PAGDEMO.*.  You can modify this and see how features are affected.  The
  207. demonstration files are as follows:
  208.  
  209. # % As is documented above, the following lines don't need a VERBATIM
  210. # % marker because they are short enough to not be affected by the JUSTIFY
  211. # % marker command.
  212.         PAGDEMO.BAT      Batch file that actually runs the demo file
  213.         PAGDEMO.#1       The primary file for the demo
  214.         PAGDEMO.#1D      The ASCII-delimited file brought in for the demo
  215.         PAGDEMO.#1C      The field-definition file used for the demo
  216.  
  217.  
  218. # index "Formatting commands"
  219. Formatting-related commands:
  220.  
  221. # index "Equal signs"
  222. The following section describes the formatting commands alphabetically with some
  223. cross-referencing.  The commands are case insensitive ("align" and "ALIGN" are
  224. the same).  Typically, the equal signs are optional ("LENGTH=80" is the same as
  225. "LENGTH 80") except when used from the DOS command line.  Remember, the text
  226. line that these commands appear in must begin with the designated marker
  227. character (typically a "#").
  228.  
  229. # index "Formatting commands" "Default values"
  230. Default initial values (format commands):
  231.         INDENT=0
  232.         LENGTH=80
  233.         MARKER=#
  234.         PAGE=60
  235.         PAGEEJECT
  236.         SINGLE
  237.         VERBATIM
  238.  
  239. # index "Formatting commands" "% (comments)"
  240. # index "% (comments)"
  241. %: Comments.  You can add comments after any marker command or you can embed
  242. them as marker commands all on their own.
  243.  
  244. # index "Formatting commands" "ADJUST"
  245. # index "ADJUST"
  246. ADJUST:  Tells the system to not write single lines on the bottom of a page.
  247. This is typically done to control "widow lines", cases where the first line of
  248. a paragraph prints on the bottom of one page and the remainder of the paragraph
  249. prints on the top of the next.
  250.  
  251. # index "Formatting commands" "-ADJUST"
  252. # index "-ADJUST"
  253. -ADJUST:  Says that "widow lines" are okay.
  254.  
  255. # index "Formatting commands" "ALIGN"
  256. # index "ALIGN"
  257. ALIGN:  Aligns text (uneven right margins) according to the default page width.
  258. See also: CENTER, JUSTIFY, RIGHT, and VERBATIM.
  259.  
  260. # index "Formatting commands" "-ALIGN"
  261. # index "-ALIGN"
  262. -ALIGN:  Same thing as VERBATIM.
  263.  
  264. # index "Formatting commands" "CENTER"
  265. # index "CENTER"
  266. CENTER:  Centers text according to the default page width.  See also: ALIGN,
  267. JUSTIFY, LENGTH, RIGHT, and VERBATIM.
  268.  
  269. # index "Formatting commands" "-CENTER"
  270. # index "-CENTER"
  271. -CENTER:  Same thing as VERBATIM.
  272.  
  273. # index "Formatting commands" "DOUBLE"
  274. # index "DOUBLE"
  275. DOUBLE:  Double-spaces all text.  See also: SINGLE, SPACING=n, and TRIPLE.
  276.  
  277. # index "Formatting commands" "EJECT"
  278. # index "EJECT"
  279. # index "Page-eject characters"
  280. EJECT: Causes a new page to be created.  A regular decimal 12 character (the
  281. female symbol) is also treated as a page eject as long as it appears by itself
  282. on a line.  See also: PAGEEJECT and PAGEFILL.
  283.  
  284. # index "Formatting commands" "EJECT FRONT"
  285. # index "EJECT FRONT"
  286. EJECT FRONT:  Same as EJECT but makes sure you are ejected to the next odd
  287. numbered page.
  288.  
  289. # index "Formatting commands" "EJECT BACK"
  290. # index "EJECT BACK"
  291. EJECT BACK:  Same as EJECT but makes sure you are ejected to the next even
  292. numbered page.
  293.  
  294. # index "Formatting commands" "FOOTER"
  295. # index "FOOTER"
  296. FOOTER ... END:  Defines a footer to appear at the bottom of each page.  Has
  297. same features that TITLE ... END has; see that discussion.
  298.  
  299. # index "Formatting commands" "INCLUDE filename"
  300. # index "INCLUDE filename"
  301. # index "Adding files"
  302. INCLUDE filename:  Adds another file to the processing.  This file is processed
  303. according to whatever formatting defaults are in use at that point.
  304.  
  305. # index "Formatting commands" "INDENT=n"
  306. # index "INDENT=n"
  307. INDENT=n:  Indents the text which follows by "n" spaces.  Essentially sets the
  308. left margin.  Default value: INDENT=0.
  309.  
  310. # index "Formatting commands" "INDENT=n-n"
  311. # index "INDENT n-n"
  312. # index "Bulleted text"
  313. INDENT=n-n:  Specifies that the most of the lines of a paragraph are to be
  314. indented by "n" spaces whereas the first word of the first line is to be
  315. indented by "n-n" spaces.  For example, "INDENT 5-3" will indent the first word
  316. by two spaces and the subsequent lines by 5 spaces.  This is frequently used for
  317. bulleted text.
  318.  
  319. # index "Bulleted text" "Tricks"
  320. Note with bulleted items that if you want single-spaced items bulleted, include
  321. a #paragraph statement before the next bullet.  This is only a problem because
  322. the routine doesn't start re-indenting text until it thinks it's at another
  323. paragraph.  (A blank line would have worked fine but you want it single spaced
  324. some times.) For example:
  325.  
  326.         # indent 5-2
  327.         * This is one paragraph to be indented
  328.         # paragraph
  329.         * And this is another.
  330.  
  331. Remember that the indentation rule applies to the first word of the first line
  332. of a given paragraph.  That word can be a bullet (like an asterisk) but it can
  333. also be an actual word.  This is useful when the first words of different
  334. paragraphs are of different lengths.  For example:
  335.  
  336.         # indent 8-8
  337.         Home Takes you to the top line
  338.         # indent 8-8
  339.         End Takes you to the bottom line
  340.         # indent 8-8
  341.         F1 Presents help
  342.  
  343. This ends up like this:
  344.  
  345.         Home    Takes you to the top line
  346.         End     Takes you to the bottom line
  347.         F1      Presents help
  348.  
  349. # index "Wrapping" "Faking out"
  350. # index "Alt-255 key"
  351. If you want, you can fake the system into thinking that multiple words are, in
  352. fact single words for indentation or word-wrapping purchases.  This is done by
  353. putting a non-printable character instead of a space character between the
  354. words.  A good character to use is Alt-255 (press the Alt key, while it's down,
  355. press the digits 2, 5, 5 on the numeric keypad, then release the Alt key).  This
  356. character shows up as a space but the system treats it as a regular character so
  357. it doesn't split up the words it's between.
  358.  
  359. Warning:  It's easy to forget you used Alt-255.  If you use Alt-255 frequently,
  360. remember to check for it with a hex text viewer (like LIST) when you're
  361. wondering why text didn't wrap or otherwise behave the way you expected.
  362.  
  363. # index "Formatting commands" "INDENT=n+n"
  364. # index "INDENT=n+n"
  365. INDENT=n+n:  Specifies that the most of the lines of a paragraph are to be
  366. indented by "n" spaces whereas the first line is to be indented by "n+n" spaces.
  367. For example, "INDENT 5+3" will indent the first line by eight spaces and the
  368. subsequent lines by 5 spaces.
  369.  
  370. # index "Formatting commands" "-INDENT"
  371. # index "-INDENT"
  372. -INDENT:  Same thing as INDENT=0.
  373.  
  374. # index "Formatting commands" "JUSTIFY"
  375. # index "JUSTIFY"
  376. JUSTIFY:  Justifies text (makes right margins flush) within the default page
  377. width.  See also:  ALIGN, CENTER, LENGTH, RIGHT, and VERBATIM.
  378.  
  379. # index "Formatting commands" "-JUSTIFY"
  380. # index "-JUSTIFY"
  381. -JUSTIFY:  Same thing as VERBATIM.
  382.  
  383. # index "Formatting commands" "LENGTH=n"
  384. # index "LENGTH=n"
  385. LENGTH=n:  Specifies the default line length.  (Page lengths are controlled by
  386. the PAGE=command.) Default value:  LENGTH=80.  See also:  ALIGN, CENTER,
  387. JUSTIFY, RIGHT, and VERBATIM.
  388.  
  389. # index "Formatting commands" "MARKER=c"
  390. # index "MARKER=c"
  391. # index "Changing marker character"
  392. MARKER=c:  Defines the single-character marker indicator that will appear in
  393. column 1 of all subsequent lines.  Default value: MARKER=#.
  394.  
  395. # index "Formatting commands" "NEXT=n"
  396. # index "NEXT=n"
  397. NEXT=n:  Specifies which page number will appear the next time ^B appears in
  398. a title, footer, or header.  You can specify "-NEXT" or "NEXT=0" to start
  399. at 0.  Starts at NEXT=1 typically.
  400.  
  401. # index "Formatting commands" "-PAGE"
  402. # index "-PAGE"
  403. -PAGE:  Same as "PAGE=0".
  404.  
  405. # index "Formatting commands" "PAGE=n"
  406. # index "PAGE=n"
  407. PAGE=n:  Defines default page length.  You can say "PAGE=0" to set continuous
  408. pages.  (You have to have a page length specified if you're using the
  409. MULTICOLUMN option though.) Default value:  PAGE=60.
  410.  
  411. # index "Formatting commands" "PAGEEJECT"
  412. # index "PAGEEJECT"
  413. PAGEEJECT:  Says that pages are to be ended with a page eject symbol (the female
  414. symbol) instead of padding the pages with blank lines).  This is the default
  415. value.  See also: PAGEFILL.
  416.  
  417. # index "Formatting commands" "PAGEFILL"
  418. # index "PAGEFILL"
  419. PAGEFILL:  Says that pages are to be ended by padding them with blank lines up
  420. to the specified PAGE=n value.  See also: PAGEEJECT.
  421.  
  422. # index "Formatting commands" "PARAGRAPH"
  423. # index "PARAGRAPH"
  424. PARAGRAPH:  Says that a new paragraph is about to begin.  This is primarily used
  425. when you have something like bulleted text which might not be properly aligned.
  426. For example:
  427.  
  428. # unit
  429. # verbatim
  430.         # align length 40 indent 5-2
  431.         * First bulleted item
  432.         # paragraph
  433.         * Second bulleted item.  Note that this would have been considered
  434.         to be part of the first paragraph since it started in column 1 and
  435.         there was no blank line between them.
  436. # end
  437.  
  438. # index "Formatting commands" "RIGHT"
  439. # index "RIGHT"
  440. RIGHT:  Moves all text to be flush to the right margin.  Doesn't adjust any
  441. spacing between words or anything.  See also:  ALIGN, CENTER, JUSTIFY, LENGTH,
  442. and VERBATIM.
  443.  
  444. # index "Formatting commands" "-RIGHT"
  445. # index "-RIGHT"
  446. -RIGHT:  Same thing as VERBATIM.
  447.  
  448. # index "Formatting commands" "SINGLE"
  449. # index "SINGLE"
  450. SINGLE:  Single-spaces all text.  This is the default spacing.  See also:
  451. DOUBLE, SPACING=n, and TRIPLE.
  452.  
  453. # index "Formatting commands" "SPACING=n"
  454. # index "SPACING=n"
  455. SPACING=n:  Sets spacing between lines as "n" number of lines.  See also:
  456. DOUBLE (which is SPACING=2), SINGLE (SPACING=1), and TRIPLE (SPACING=3).
  457.  
  458. # index "Formatting commands" "TITLE"
  459. # index "TITLE"
  460. TITLE ...  END:  Defines a title to appear at the top of each page.  Any number
  461. of lines can appear in the title.  The title ends with a marker line that
  462. contains the "end" command; if no "end" command is provided, the program
  463. presumes there is one after the last line of your file.  Spacing, indentation,
  464. length, and alignment cannot vary within the title; the last one assigned will
  465. win.  See "control codes" discussion below for characters that can appear in the
  466. title.  To eliminate the title, define a title without any lines in it.  See
  467. also:  FOOTER ...  END, HEADER ...  END and UNIT ...  END.  Example:
  468.  
  469.         # title center length=80
  470.         This is my program!
  471.  
  472.         # end
  473.  
  474. # index "Formatting commands" "TRIPLE"
  475. # index "TRIPLE"
  476. TRIPLE:  Triple-spaces all text.  See also: DOUBLE, SINGLE, and SPACING=n.
  477.  
  478. # index "Formatting commands" "UNIT"
  479. # index "UNIT"
  480. UNIT ... END:  Defines a unit of text with its own unique formatting.  Units
  481. can have formatting which differs from the text around it and changing the
  482. formatting within the Unit will not affect the other text.  Has same features
  483. that TITLE ... END has; see that discussion.
  484.  
  485. A typical use for the UNIT command is in combination with VERBATIM.  This is
  486. frequently used when you're aligning or justifying most of the text and then you
  487. have one section that isn't to be changed at all.
  488.  
  489. # index "Formatting commands" "VERBATIM"
  490. # index "VERBATIM"
  491. VERBATIM:  Specifies that the text which follows should not be aligned,
  492. justified, etc.  See also: ALIGN, CENTER, JUSTIFY, and RIGHT.
  493.  
  494.  
  495. # index "Database-related commands"
  496. Database-related functions:
  497.  
  498. The PAGINATE command provides some features to allow you to use it to read in
  499. and print out ASCII-delimited and dBase files.  For example:
  500.  
  501.         # from ascii
  502.         "Apples",10,5
  503.         "Bananas",20,10
  504.  
  505. will come out as:
  506.  
  507.         Apples   10  5
  508.         Bananas  20 10
  509.  
  510. You can use this capability to imbed tables within a report.  You can also
  511. combine this with SORT=varspec and SELECT=varspec specifications to have the
  512. report sorted on specified columns or to subset the columns that get printed
  513. out.  There are some restrictions to all of this and these are described within
  514. each option as appropriate below.
  515.  
  516. NOTE:  In general, combining FROM ASCII or FROM DBF or several of the other
  517. data-base related functions with options like ALIGN and JUSTIFY will not work.
  518. The formatting options will, in general, be ignored.
  519.  
  520. # index "Sorting" "Example"
  521. It's often the case that you will want to deal only with a single data set,
  522. and you'll have no need for actual text.  For example, let's say that you really
  523. want something that will sort a file that contains a lot of data.  No problem:
  524.  
  525.         PAGINATE infile outfile /-PAGE /SORT=1,10
  526.  
  527. # index "dBase files" "Example"
  528. Another example would be that you have something like a dBase file and you want
  529. to print it out.  Again, no problem.  Create a simple control file:
  530.  
  531. # unit
  532. # verbatim
  533.         # heading
  534.         ^H
  535.  
  536.         # end
  537.         # from dbf
  538.         # include sample.dbf
  539. # end
  540.  
  541. and then create your tables with:
  542.  
  543.         PAGINATE ctlfile outfile
  544.  
  545.  
  546. # index "Database-related commands" "Default values"
  547. Default initial values (database-related functions):
  548.  
  549.         BAD=ABORT
  550.         -DELETED
  551.         DELIMS=",,,
  552.         FROM FIXED
  553.         GAP=2
  554.         INMISS=NULL
  555.         INMISSC=NULL
  556.         OUTMISS=NULL
  557.         OUTMISSC=NULL
  558.         SELECT=NULL
  559.         SEPARATOR=" | "
  560.         SORT=NULL
  561.         SUM=NULL
  562.         -TALLY
  563.  
  564. # index "Database-related commands" "BAD=ABORT"
  565. # index "BAD=ABORT"
  566. BAD=ABORT:  Says that if the program runs into an invalid data value,
  567. it should abort processing entirely.
  568.  
  569. # index "Database-related commands" "BAD=MISSING"
  570. # index "BAD=MISSING"
  571. BAD=MISSING:  Says that if the program runs into an invalid data value, it
  572. should set the value of that variable as "missing" and continue processing.
  573.  
  574. # index "Database-related commands" "BAD=SKIP"
  575. # index "BAD=SKIP"
  576. BAD=SKIP:  Says that if the program runs into an invalid data value, it should
  577. skip the entire data record and continue processing with the next record.
  578.  
  579. # index "Database-related commands" "DELETED"
  580. # index "DELETED"
  581. DELETED:  Says to process deleted records as well as non-deleted records from
  582. dBase files.
  583.  
  584. # index "Database-related commands" "-DELETED"
  585. # index "-DELETED"
  586. -DELETED:  Says to skip deleted records.
  587.  
  588. # index "Database-related commands" "DELIMS"
  589. # index "DELIMS"
  590. # index "Hexadecimal codes"
  591. DELIMS=aroundstrings,aroundnums,betweenfields:  Allows you to specify the
  592. delimiters (in sequence) around string fields, around numeric fields, and
  593. between fields.  Defaults to:
  594.  
  595.         DELIMS=",,,
  596.  
  597. (Use quotes around character strings, nothing around numeric data, and the third
  598. comma indicates that there is a comma between fields.) The replacement string
  599. can include hexadecimal codes (in the &Hxx format) or decimal codes (in the \ddd
  600. format) if necessary so either of the following would put a tab between fields:
  601.  
  602.         DELIMS=",,&H09
  603.         DELIMS=",,\009
  604.  
  605. See the table of hexadecimal and decimal codes at the end of this documentation.
  606.  
  607. # index "Database-related commands" "FROM ASCII"
  608. # index "FROM ASCII"
  609. # index "ASCII-delimited files"
  610. # index "Files" "ASCII-delimited"
  611. FROM ASCII:  Specifies that the next non-marker lines contain ASCII-delimited
  612. records.  The ASCII-delimited records can be embedded within the report or
  613. stored as a separate file (brought in with an INCLUDE statement).  See also:
  614. FROM DBF and FROM FIXED and most of the other commands in this section.  See
  615. also:  "Field-definition file" discussion.
  616.  
  617. # index "Database-related commands" "FROM DBF"
  618. # index "FROM DBF"
  619. # index "dBase files"
  620. # index "Files" "dBase"
  621. FROM DBF:  Specifies that the next INCLUDE statement is a dBase file.  Unlike
  622. with FROM FIXED and FROM ASCII, the dBase file has to be external to the control
  623. cards.  The output itself, however, will be included with the regular output
  624. file.  See also: FROM ASCII and FROM FIXED and most of the other commands in
  625. this section.  See also: "Field-definition file" discussion.
  626.  
  627. # index "Database-related commands" "FROM FIXED"
  628. # index "FROM FIXED"
  629. FROM FIXED:  Specifies that the input file is a fixed-field file.  This is
  630. typical for most text files.  See also: FROM ASCII and FROM DBF.
  631.  
  632. # index "Database-related commands" "-GAP"
  633. # index "-GAP"
  634. -GAP:  Same as "GAP=0".
  635.  
  636. # index "Database-related commands" "GAP=n"
  637. # index "GAP=n"
  638. GAP=n:  Specifies the number of spaces to appear between columns when printing
  639. fielded data.  If, for example, two columns of numbers are printed, the GAP
  640. parameter specifies that "n" number of spaces are to appear between these
  641. columns.  You can specify "GAP=0" if you don't want any gap to be inserted.
  642. Defaults to GAP=2.
  643.  
  644. # index "Database-related commands" "HEADER"
  645. # index "HEADER"
  646. # index "Column headers"
  647. HEADER ... END:  Defines a set of column headers that should appear before
  648. the actual data.  Typically, you can bring these in from the actual dBase file
  649. or else use whatever you've specified in the field-definition file by using the
  650. "^H" control code.  Headers are affected by the MULTICOLUMN specification.
  651. Otherwise, they are treated pretty much like Titles and Footers.  See the
  652. discussion of TITLE ... END.
  653.  
  654. # index "Database-related commands" "INCLUDE filename"
  655. # index "INCLUDE filename"
  656. # index "Files" "Adding"
  657. INCLUDE filename:  Adds text from another file in at this point.  If the routine
  658. has been told that this is a FROM DBF or FROM ASCII file, it will process the
  659. file appropriately.  The filename specification can include drive and path
  660. information if desired.
  661.  
  662. # index "Database-related commands" "INCLUDE INDEX"
  663. # index "INCLUDE INDEX"
  664. INCLUDE INDEX:  Creates an index listing at this point in the document.  See
  665. also: INDEX.
  666.  
  667. # index "Database-related commands" "INDEF filename"
  668. # index "INDEF filename"
  669. # index "Field-definition file"
  670. INDEF filename:  Specifies that the file characteristics for the input file
  671. which follows are contained in a field-definition file specified as "filename".
  672. The filename spec can include drive and path information if desired.  See the
  673. discussion of "Field-definition files" below.  See also: INDEF NULL.
  674.  
  675. # index "Database-related commands" "INDEF NULL"
  676. # index "INDEF NULL"
  677. INDEF NULL:  Says there is no input file definition for what follows.  Typically
  678. used to turn off the previously-specified input field-definition file.  See
  679. also: INDEF filename.
  680.  
  681. # index "Database-related commands" "-INDEF"
  682. # index "-INDEF"
  683. -INDEF:  Same thing as INDEF NULL.
  684.  
  685. # index "Database-related commands" "INDEX"
  686. # index "INDEX"
  687. # index "See Also references"
  688. INDEX "word" [ "word" ]...  [DUMMY]:  Saves an index record, with the specified
  689. text and the current page number, at this point.  The index is then printed out
  690. when you add an INCLUDE INDEX option.  The multiple word specifications allow
  691. you to specify up to 3 levels of indexing.  For example,
  692.  
  693.         # index "Computers" "Maintenance"
  694.         # index "Computers" "Hardware"
  695.         # eject
  696.         # index "Computers" "Hardware"
  697.         # index "Computers" "Software"
  698.         # include index
  699.  
  700. will generate output that looks in part like this:
  701.  
  702.         Computers
  703.           Hardware; 1, 2
  704.           Maintenance; 1
  705.           Software; 2
  706.  
  707. # index "MULTICOLUMN" "With INDEX"
  708. # index "INDEX" "With MULTICOLUMN"
  709. You can use MULTICOLUMN in combination with the INDEX command.  Just make sure
  710. you specify the MULTICOLUMN before the INCLUDE INDEX statement as in:
  711.  
  712.         # multicolumn 3
  713.         # include index
  714.  
  715. # index "DUMMY index references"
  716. If DUMMY is specified, the page number is not displayed for this item.  This is
  717. typically done when you want the index to provide a cross-reference but you
  718. don't really want any page numbers showing up.  For example:
  719.  
  720.         # index "Hardware" "(See Computers)" DUMMY
  721.  
  722. My personal preference is to put all DUMMY index references near the start of
  723. your document so you can find them more easily.
  724.  
  725. # index "Database-related commands" "INMISS=val"
  726. # index "INMISS=val"
  727. INMISS=val:  Specifies for ASCII-delimited and dBase input files which numeric
  728. values are to be considered indicators for missing values.  Missing values
  729. are not included in summations.  Defaults to INMISS=NULL.  See also:
  730. INMISSC=val, OUTMISS=val, and OUTMISSC=val.
  731.  
  732. # index "Database-related commands" "INMISSC=val"
  733. # index "INMISSC=val"
  734. INMISSC=val:  Specifies for ASCII-delimited and dBase input files which
  735. character values are to be considered indicators for missing values.  Defaults
  736. to INMISSC=NULL.  See also: INMISS=val, OUTMISS=val, and OUTMISSC=val.
  737.  
  738. # index "Database-related commands" "MULTICOLUMN"
  739. # index "MULTICOLUMN"
  740. # index "SEPARATOR" "With MULTICOLUMN"
  741. MULTICOLUMN=n ...  END:  Specifies that a given block is to be arranged in a
  742. multicolumn format.  The number of columns is specified as "n"; "MULTICOLUMN=2"
  743. would set up a dual-column output.  The SEPARATOR string appears between each of
  744. the columns.  (MULTICOLUMN", by the way, can be abbreviated "MULTI" or
  745. "MULTICOL".) Make sure you put any CENTER or ALIGN or whatever statements after
  746. the MULTICOLUMN statement.  Also note that you can specify a length
  747. ("MULTICOLUMN=2 LENGTH=80") but the program internally recalculates the length
  748. of each segment each time as the total line length (typically 80) divided by the
  749. number of columns minus the width of the separator string.  Otherwise,
  750. MULTICOLUMN has the same features that TITLE ...  END has; see that discussion.
  751. (Remember, unless provided otherwise, the "END" command is presumed to be after
  752. the last line of your input file.)  See also:  SEPARATOR=string.  Example:
  753.  
  754.         # multicolumn 3 separator=" | "
  755.         lines
  756.         lots of lines
  757.         still more
  758.         # end
  759.  
  760. # index "Database-related commands" "NULLS"
  761. # index "NULLS"
  762. NULLS:  Says that the program will accept values that begin with a decimal
  763. zero as being a valid value.  Defaults to NULLS.  See also: -NULLS.
  764.  
  765. # index "Database-related commands" "-NULLS"
  766. # index "-NULLS"
  767. -NULLS:  Says that values which begin with a decimal zero should be treated
  768. as missing by the program.  Defaults to NULLS.  See also: NULLS.
  769.  
  770. # index "Database-related commands" "OUTDEF filename"
  771. # index "OUTDEF filename"
  772. # index "Field-definition file"
  773. OUTDEF filename:  Specifies the field-definition file to create.  Typically, the
  774. only reason you'd ever use this command is if you want the program to create a
  775. field-definition file for a dBase input file.  (See the discussion of
  776. "Field-definition file" later.)  See also:  OUTDEF NULL.
  777.  
  778. # index "Database-related commands" "OUTDEF NULL"
  779. # index "OUTDEF NULL"
  780. OUTDEF NULL:  Turns off the output field-definition file specification.  See
  781. also: OUTDEF filename.
  782.  
  783. # index "Database-related commands" "-OUTDEF"
  784. # index "-OUTDEF"
  785. -OUTDEF:  Same as OUTDEF NULL.
  786.  
  787. # index "Database-related commands" "OUTMISS=val"
  788. # index "OUTMISS=val"
  789. OUTMISS=val:  Specifies what value will be substituted for missing numeric
  790. input values on output.  Initially defaults to OUTMISS=NULL.  See also:
  791. INMISS=val, INMISSC=val, and OUTMISSC=val.
  792.  
  793. # index "Database-related commands" "OUTMISSC=val"
  794. # index "OUTMISSC=val"
  795. OUTMISSC=val:  Specifies what value will be substituted for missing character
  796. input values on output.  Initially defaults to OUTMISSC=NULL.  See also:
  797. INMISS=val, INMISSC=val, and OUTMISS=val.
  798.  
  799. # index "Database-related commands" "RESET=string"
  800. # index "RESET=string"
  801. RESET=string:  Specifies a character string to stick at the end of the file, to
  802. reset the printer after the document is printed.  A page eject is typically
  803. added automatically if /EJECT is specified.  The string can contain special
  804. characters by using a "\" followed by the three-digit ASCII code for the
  805. character.  The typical use for this would be to issue a printer
  806. reinitialization string.  On a Hewlett-Packard printer, this would probably be
  807. RESET=\027E.  See also:  SETUP=string.
  808.  
  809. # index "Database-related commands" "SELECT=varspec"
  810. # index "SELECT=varspec"
  811. SELECT=varspec:  Specifies which variables or columns should show up in the
  812. ultimate file.  This allows you to take, for example, a text file and only print
  813. the middle 10 columns of it or else to take a dBase file and only print certain
  814. variables.  See the discussion of "Varspecs" later.  See also: SELECT=NULL.
  815.  
  816. # index "Database-related commands" "SELECT=NULL"
  817. # index "SELECT=NULL"
  818. SELECT=NULL:  Specifies that all variables or columns should show up.  This is
  819. initially the default.  See also: SELECT=varspec.
  820.  
  821. # index "Database-related commands" "-SELECT"
  822. # index "-SELECT"
  823. -SELECT:  Same thing as SELECT=NULL.
  824.  
  825. # index "Database-related commands" "SEPARATOR"
  826. # index "SEPARATOR"
  827. SEPARATOR=string:  Specifies the string to appear between columns in a
  828. multicolumn output.  The string can contain special characters by using a "\"
  829. followed by the three-digit ASCII code for the character.  For example, to have
  830. a graphic vertical bar, use SEPARATOR=\032\179\032 or else enter it directly as
  831. SEPARATOR=" │ ".  Initially defaults to SEPARATOR=" | ".  See also:
  832. MULTICOLUMN=n.
  833.  
  834. # index "Database-related commands" "SETUP=string"
  835. # index "SETUP=string"
  836. SETUP=string:  Specifies the character string to strick at the beginning of the
  837. file, to initialize the printer before the document is printed.  Typically, you
  838. might use an initialization string that sets the printer in compressed,
  839. landscape, or whatever mode.  The string can contain special characters by using
  840. a "\" followed by the three-digit ASCII code for the character.  On a
  841. Hewlett-Packard printer, this would typically be one of the following codes:
  842.  
  843.         SETUP=\027E             (portrait mode, 80 column)
  844.         SETUP=\027E\027(s16.66H (portrait mode, 132 column)
  845.  
  846. On an Epson MX dot-matrix printer, you would typically use these codes:
  847.  
  848.         SETUP=\015              (portrait mode, 80 column)
  849.         SETUP=\018              (portrait mode, 132 column)
  850.  
  851. See also: RESET=string.
  852.  
  853. # index "Database-related commands" "SORT=varspec"
  854. # index "SORT=varspec"
  855. SORT=varspec:  Specifies that the lines should be sorted according to a
  856. particular group of columns or variables.  See the discussion of "Varspecs"
  857. later.  Sorting is done based on a case-sensitive search ("Apple" and "Banana"
  858. will appear before "air").  Note that sorting works well for character strings
  859. but negative numbers can cause it all sorts of problems.  The sort field
  860. specification is limited to 50 characters.  Note that you cannot combine sorting
  861. specifications (e.g.  descending for some columns and ascending for others.)
  862. Initially defaults to SORT=NULL.  See also:  SORT=NULL.  Basic sorting
  863. specifications available here (see each separately):
  864.  
  865.         SORT      --> case-sensitive, ascending sort
  866.         SORTD     --> case-sensitive, descending sort
  867.         SORTI     --> case-insensitive, ascending sort
  868.         SORTDI    --> case-insensitive, descending sort
  869.         SORTID    --> case-insensitive, descending sort
  870.  
  871. # index "Database-related commands" "SORT=NULL"
  872. # index "SORT=NULL"
  873. SORT=NULL:  Turns off any sorting specification.  This statement is vital if you
  874. have any text appearing after a sorted section.  Remember, you cannot have
  875. multiple sorting specifications going on so this is the same as all of the
  876. following:  -SORT, -SORTI, -SORTD, -SORTID, -SORTDI, SORTI=NULL, SORTD=NULL,
  877. SORTDI=NULL, and SORTID=NULL.  This statement is initially the default.
  878.  
  879. # index "Database-related commands" "-SORT"
  880. # index "-SORT"
  881. -SORT:  Same as SORT=NULL.
  882.  
  883. # index "Database-related commands" "SORTD=varspec"
  884. # index "SORTD=varspec"
  885. SORTD=varspec:  Similar to SORT=varspec but sorting is done in descending
  886. sequence.  See SORT=varspec and SORT=NULL.
  887.  
  888. # index "Database-related commands" "SORTD=NULL"
  889. # index "SORTD=NULL"
  890. SORTD=NULL:  Same as SORT=NULL.
  891.  
  892. # index "Database-related commands" "-SORTD"
  893. # index "-SORTD"
  894. -SORTD:  Same as SORT=NULL.
  895.  
  896. # index "Database-related commands" "SORTDI=varspec"
  897. # index "SORTDI=varspec"
  898. SORTDI=varspec:  Similar to SORT=varspec but sorting is done in descending
  899. sequence and sorting is case insensitive.  Identical to SORTID=varspec.  See
  900. SORT=varspec and SORT=NULL.
  901.  
  902. # index "Database-related commands" "SORTDI=NULL"
  903. # index "SORTDI=NULL"
  904. SORTDI=NULL:  Same as SORT=NULL.
  905.  
  906. # index "Database-related commands" "-SORTDI"
  907. # index "-SORTDI"
  908. -SORTDI:  Same as SORT=NULL.
  909.  
  910. # index "Database-related commands" "SORTI=varspec"
  911. # index "SORTI=varspec"
  912. SORTI=varspec:  Same as SORT=varspec except the sorting is done in a
  913. case-insensitive manner ("big" shows up between "Apple" and "Caramel").  See
  914. SORT=varspec and SORT=NULL.
  915.  
  916. # index "Database-related commands" "SORTI=NULL"
  917. # index "SORTI=NULL"
  918. SORTI=NULL:  Same as SORT=NULL.
  919.  
  920. # index "Database-related commands" "-SORTI"
  921. # index "-SORTI"
  922. -SORTI:  Same as SORT=NULL.
  923.  
  924. # index "Database-related commands" "SORTID=varspec"
  925. # index "SORTID=varspec"
  926. SORTID=varspec:  Same as SORTDI=varspec.
  927.  
  928. # index "Database-related commands" "SORTID=NULL"
  929. # index "SORTID=NULL"
  930. SORTID=NULL:  Same as SORT=NULL.
  931.  
  932. # index "Database-related commands" "-SORTID"
  933. # index "-SORTID"
  934. -SORTID:  Same as SORT=NULL.
  935.  
  936.  
  937.  
  938. # index "Control codes"
  939. # index "Page numbers"
  940. # index "Date-stamps"
  941. # index "Time-stamps"
  942. # index "Column headers"
  943. # index "^B"
  944. # index "^D"
  945. # index "^T"
  946. # index "^N"
  947. # index "^A"
  948. # index "^I"
  949. # index "^H"
  950. Control codes:
  951.  
  952. Within titles, headers, and footers, you can embed the following codes.  These
  953. codes are case-sensitive; "^b^" will not translated as the current page number.
  954. These codes will be expanded on output:
  955.  
  956.         ^B      current page number
  957.         ^D      pagination date (in mm/dd/yy format)
  958.         ^T      pagination time (in hh:mm format)
  959.         ^N      name of the input file (without drive or path information)
  960.         ^A      input file's creation date (in mm/dd/yy format)
  961.         ^I      input file's creation time (in hh:mm format)
  962.         ^H      column headers (when appropriate)
  963.  
  964. Note that formatting commands like centering will be adjusted based on the
  965. replacement contents for these codes.  A line containing a one-digit page number
  966. will be centered differently than the exact same line containing a three-digit
  967. page number.
  968.  
  969. Example:
  970.  
  971.         # title center length 80
  972.         File ^N listing, page ^B
  973.  
  974.         # end
  975.  
  976.  
  977.  
  978. # index "Varspecs"
  979. # index "Specifying columns"
  980. # index "Specifying variables"
  981. # index "Columns" "Specifying"
  982. Varspecs:
  983.  
  984. Several of the commands (e.g.  SELECT and SORT) expect you to pass in a
  985. "varspec" parameter.  Varspec's indicate which variables or columns to process.
  986.  
  987. The format for the varspec is:
  988.  
  989.         n[-n] [ , n-[n] ]...
  990.  
  991. where "n" is a single variable/column.  "n-n" indicates you want a range of
  992. variables/columns.
  993.  
  994. For FROM ASCII or FROM DBF, the "n" corresponds to a variable number.  For FROM
  995. FIXED, the "n" corresponds to a physical one-byte column.  For example:
  996.  
  997.         # from ascii
  998.         # select 1,3
  999.         "Testing",2,4
  1000.         "All",5,7
  1001.         "This",1,6
  1002.  
  1003. says to display the 1st and 3rd variables and results in something like this:
  1004.  
  1005.         Testing  4
  1006.         All      7
  1007.         This     6
  1008.  
  1009. On the other hand, if you're processing fixed-fielded data, the varspec will
  1010. select individual columns.  So:
  1011.  
  1012.         # from fixed
  1013.         # select 1-10,15
  1014.         1234567_10_2345678
  1015.         Testing   abcdefgh
  1016.         All       abcdefgh
  1017.         This      abcdefgh
  1018.  
  1019. will come out like this:
  1020.  
  1021.         Testing   e
  1022.         All       e
  1023.         This      e
  1024.  
  1025.  
  1026. # index "Field-definition file"
  1027. # index "ASCII-delimited files"
  1028. # index "dBase files"
  1029. Field-definition file:
  1030.  
  1031. For data files (ASCII-delimited, dBase, and fixed field input files), you can
  1032. use PAGINATE.EXE to present a reasonably formatted listing of variables.  Unless
  1033. you are reading a dBase file, this program requires a field-definition file to
  1034. figure out the characteristics for each field and also to set certain file
  1035. characteristics.  If you're processing an ASCII-delimited input file, the
  1036. routine can try to create a field-definition file for you if desired.
  1037.  
  1038. The definition file can be created with any text editor.  The definition file
  1039. consists of several records with the following fields separated by spaces.
  1040. Except for the record type indicator (which must begin in column 1), all other
  1041. fields can be placed in any columns:
  1042.  
  1043.         (1) record type (see below)
  1044.         (2) length of field on input
  1045.         (3) number of decimal places for numeric data (if you don't know,
  1046.             put a "?" here; for non-numeric data, a "0" is fine) on output
  1047.         (4) length of field on output
  1048.  
  1049. Any characters after the field length are treated as comment fields.  You would
  1050. typically use this to enter the field name or column position or any other
  1051. information of use to you.
  1052.  
  1053. The data record types accepted by this routine are as follows:
  1054.  
  1055.         type C = character data
  1056.              N = numeric
  1057.              L = logical (T or F)
  1058.              D = date (in yyyymmdd format)
  1059.  
  1060. The data fields should be in the order the fields are found in the source file.
  1061.  
  1062. Note that for fixed field files, you have to account for every byte in the file.
  1063. If you have something like this:
  1064.  
  1065.         12345678_1_2345678_2_2345678_3      (column positions)
  1066.         APPLE    X Y    12 BANANAS
  1067.  
  1068. Even though you may think you only have five fields, the following .DEF file
  1069. will NOT work:
  1070.  
  1071.         ; Bad .DEF file:  Note does not account for blank spaces
  1072.         C   8 0   8 Fruit1
  1073.         C   1 0   1 Class1
  1074.         C   1 0   1 Class2
  1075.         N   5 0   5 Value
  1076.         C  11 0  11 Fruit2
  1077.  
  1078.  
  1079. You may want the Fruit1 field to be in columns 1 through 8 and Class1 to be in
  1080. column 10 but the routine will not know to skip column 9 so it will start
  1081. reading Class1 beginning in column 9, Class2 beginning in column 10, etc.  To
  1082. drop the blank positions, you have to add dummy fields on input and ask for them
  1083. to be dropped on output:
  1084.  
  1085.         ; Good .DEF file:  Spaces between fields are accounted for
  1086.         C   8 0   8 Fruit1
  1087.         C   1 0   0 Filler
  1088.         C   1 0   1 Class1
  1089.         C   1 0   0 Filler
  1090.         C   1 0   1 Class2
  1091.         C   1 0   0 Filler
  1092.         N   5 0   5 Value
  1093.         C   1 0   0 Filler
  1094.         C  11 0  11 Fruit2
  1095.  
  1096. You can also use the input field length and output field lengths to either drop
  1097. fields using other formats (by specifying a zero length for the output field
  1098. length) or for creating fields on output (by specifying a zero length for the
  1099. input field length).  You can also use this to expand on contract a field.  For
  1100. example, if Fruit1 is 8 characters long but you only want it to occupy 4
  1101. characters on output (thus the field would be truncated), specify 8 for the
  1102. input field length and 4 for the output field length.
  1103.  
  1104.  
  1105. # index "Command-line options"
  1106. # index "Marker commands"
  1107. # index "DOS command-line options"
  1108. # index "/ vs #"
  1109. Commands which can appear both in marker lines and at the DOS command line:
  1110.  
  1111. Note that these commands typically begin with a "#" within marker commands and
  1112. multiple commands can be specified with a single marker command.  From the DOS
  1113. command line, however, you must begin each with a "/".  Each functions
  1114. identically to the way the marker command does and can be overridden with
  1115. subsequent marker commands imbedded in the files themselves.
  1116.  
  1117. Note that while just about every marker command can be specified in the DOS
  1118. command line, some of the parms (like EJECT) aren't all that useful from the
  1119. command line.  Several commands (like FOOTER and HEADER) have no usefulness on
  1120. the command line at all and are listed as "(don't use)" here.
  1121.  
  1122.         Marker command:              DOS command line parm:
  1123.  
  1124.         % comments                   (don't use)
  1125.         ADJUST                       /ADJUST
  1126.         -ADJUST                      /-ADJUST
  1127.         ALIGN                        /ALIGN
  1128.         -ALIGN                       /-ALIGN
  1129.         CENTER                       /CENTER
  1130.         -CENTER                      /-CENTER
  1131.         DOUBLE                       /DOUBLE
  1132.         EJECT                        /EJECT
  1133.         EJECT FRONT                  /EJECT FRONT
  1134.         EJECT BACK                   /EJECT BACK
  1135.         FOOTER ... END               (don't use)
  1136.         INCLUDE filename             (don't use)
  1137.         INDENT=n                     /INDENT=n
  1138.         INDENT=n-n                   /INDENT=n-n
  1139.         INDENT=n+n                   /INDENT=n+n
  1140.         -INDENT                      /-INDENT
  1141.         JUSTIFY                      /JUSTIFY
  1142.         LENGTH=n                     /LENGTH=n
  1143.         MARKER=c                     /MARKER=c
  1144.         NEXT=n                       /NEXT=n
  1145.         PAGE=n                       /PAGE=n
  1146.         PAGEEJECT                    /PAGEEJECT
  1147.         PAGEFILL                     /PAGEFILL
  1148.         PARAGRAPH                    (don't use)
  1149.         RIGHT                        /RIGHT
  1150.         SINGLE                       /SINGLE
  1151.         SPACING=n                    /SPACING=n
  1152.         TITLE  ... END               (don't use)
  1153.         TRIPLE                       /TRIPLE
  1154.         UNIT   ... END               (don't use)
  1155.         VERBATIM                     /VERBATIM
  1156.  
  1157.  
  1158.         Database command:            DOS command line parm:
  1159.  
  1160.         BAD=ABORT                    /BAD=ABORT
  1161.         BAD=MISSING                  /BAD=MISSING
  1162.         BAD=SKIP                     /BAD=SKIP
  1163.         DELETED                      /DELETED
  1164.         -DELETED                     /-DELETED
  1165.         DELIMS=val,val,val           /DELIMS=val,val,val
  1166.         FROM ASCII                   /FROM=ASCII
  1167.         FROM DBF                     /FROM=DBF
  1168.         FROM FIXED                   /FROM=FIXED
  1169.         GAP=n                        /GAP=n
  1170.         HEADER ... END               (don't use)
  1171.         INCLUDE filename             (don't use)
  1172.         INCLUDE INDEX                (don't use)
  1173.         INDEF=filename               /INDEF=filename
  1174.         INDEF=NULL                   /INDEF=NULL
  1175.         -INDEF                       /-INDEF
  1176.         INDEX "word" ["word"]...     (don't use)
  1177.         INMISS=val                   /INMISS=val
  1178.         INMISSC=val                  /INMISSC=val
  1179.         MULTICOLUMN=n ... END        /MULTICOLUMN=n
  1180.         NULLS                        /NULLS
  1181.         -NULLS                       /-NULLS
  1182.         OUTDEF=filename              /OUTDEF=filename
  1183.         OUTDEF=NULL                  /OUTDEF=NULL
  1184.         -OUTDEF                      /-OUTDEF
  1185.         OUTMISS=val                  /OUTMISS=val
  1186.         OUTMISSC=val                 /OUTMISSC=val
  1187.         RESET=string                 /RESET=string
  1188.         SELECT=varspec               /SELECT=varspec
  1189.         SELECT=NULL                  /SELECT=NULL
  1190.         -SELECT                      /-SELECT
  1191.         SEPARATOR=string             /SEPARATOR=string
  1192.         SETUP=string                 /SETUP=string
  1193.         SORT=varspec                 /SORT=varspec
  1194.         SORT=NULL                    /SORT=NULL
  1195.         -SORT                        /-SORT
  1196.         SORTD=varspec                /SORTD=varspec
  1197.         SORTD=NULL                   /SORTD=NULL
  1198.         -SORTD                       /-SORTD
  1199.         SORTDI=varspec               /SORTDI=varspec
  1200.         SORTDI=NULL                  /SORTDI=NULL
  1201.         -SORTDI                      /-SORTDI
  1202.         SORTI=varspec                /SORTI=varspec
  1203.         SORTI=NULL                   /SORTI=NULL
  1204.         -SORTI                       /-SORTI
  1205.         SORTID=varspec               /SORTID=varspec
  1206.         SORTID=NULL                  /SORTID=NULL
  1207.         -SORTID                      /-SORTID
  1208.  
  1209.  
  1210.  
  1211. # index "Parameters" "Specifying"
  1212. # index "INI file"
  1213. # index "SET PAGINATE environmental variable"
  1214. Specifying parameters:
  1215.  
  1216. Parameters for this program can be set in the following ways.  The last setting
  1217. encountered always wins:
  1218.   - Read from an *.INI file (see below),
  1219.   - Through the use of an environmental variable (SET AV=whatever), or
  1220.   - From the command line (see "Syntax" below)
  1221.  
  1222.  
  1223. # index "INI file"
  1224. The PAGINATE.INI file:
  1225.  
  1226. PAGINATE will read a PAGINATE.INI file if one is found.  (You can specify a
  1227. different file name if desired.) The file is an ASCII text file that can be
  1228. created maintained by hand.  The file can consist or one or more command line
  1229. parameters (only those that begin with a "/"; no multi-word ones), one statement per line.
  1230.  
  1231. The file can also contain comments which are blank lines or any line beginning
  1232. with:
  1233.         ;    (semi-colon)
  1234.         :    (colon)
  1235.         '    (quote)
  1236.  
  1237. PAGINATE looks for the initialization file in your default subdirectory first.
  1238. It then searches for it in the subdirectory where the executable was and then
  1239. goes through your DOS path.
  1240.  
  1241. Passing in "/-I" or "/INULL" skips loading the INI file.  This saves some
  1242. execution time as the program does not need to search your path for the file.
  1243.  
  1244.  
  1245.  
  1246. # index "Examples"
  1247. # index "Directories" "Multicolumn"
  1248. Examples:
  1249.  
  1250. This section adds some examples of how you can use PAGINATE.  I'll add to it
  1251. over time.
  1252.  
  1253. Multicolumn Directories:  You want to generate a multicolumn listing of
  1254. directories which are sorted going down the page instead of across the page
  1255. like "DIR /W" does.  PAGINATE can handle this fairly easily.
  1256.  
  1257. Create a control file called C:\DIRW.CTL with these statements (the SETUP and
  1258. RESET statements work for Hewlett-Packard printers to put you into compressed
  1259. mode):
  1260.  
  1261.         #LENGTH 132
  1262.         #SETUP "\027E"
  1263.         #RESET "\027E\027(s16.66H"
  1264.         #MULTICOLUMN 7
  1265.  
  1266. Then create a batch file called DIRW.BAT:
  1267.  
  1268.         DIR /ON > TEMP.TXT
  1269.         PAGINATE TEMP.TXT TEMP.OUT /CC:\DIRW.CTL /OVERWRITE
  1270.         DEL TEMP.TXT
  1271.  
  1272. This will route your directory to a disk file and rewrite it as TEMP.OUT in a
  1273. multicolumn format with printer controls.
  1274.  
  1275.  
  1276. #
  1277. # index "Transition notes"
  1278. # index "MULTICOL program"
  1279. Transition notes:
  1280.  
  1281. The PAGINATE command is in early release.  I expect to add a number of features
  1282. but they'll be put in on an as-possible basis.
  1283.  
  1284. PAGINATE.EXE is designed to replace my MULTICOL.EXE program which, over time,
  1285. I've felt has the wrong focus.  I'm finding myself using MULTICOL primarily to
  1286. add footers to text files.  While it can do this okay within limits, a more
  1287. full-featured reformatter would suit this task better.  I figured if I started
  1288. from scratch with PAGINATE.EXE, I could get a decent replacement without having
  1289. to worry about affecting existing code.  Of course, PAGINATE and MULTICOL (and
  1290. CONVERT.EXE) use some of the same subroutines so changes in one place are
  1291. affecting the other routines.  Sorry about that!  I hope things still work.
  1292.  
  1293. Major differences at this point between PAGINATE.EXE and MULTICOL.EXE are the
  1294. following:
  1295.  
  1296. # unit
  1297. # indent 4-2
  1298. * MULTICOL expected you to pass in the formatting controls from the DOS command
  1299. lines (or use a control file).  There was only one set of controls which could
  1300. be applied.  PAGINATE, on the other hand, typically expects the controls to be
  1301. embedded directly in the text (although it allows you to pass most of them in or
  1302. use a control file).  Formatting specifications can change throughout the text.
  1303.  
  1304. * MULTICOL had a limited number of formatting options.  PAGINATE, since it uses
  1305. embedded commands, could in theory due lots of new things.
  1306.  
  1307. * MULTICOL handled dBase and ASCII-delimited files.  PAGINATE has to add these
  1308. still.  Most of the MULTICOL features (and parameters) will be added to PAGINATE
  1309. when I get the chance.
  1310.  
  1311. * On large documents, the best that MULTICOL could really do was add headers and
  1312. page ejects.  PAGINATE is designed to provide flexibility for large documents.
  1313.  
  1314. * The MULTICOL command let you specify titles, footers, and column headers from
  1315. the command line.  PAGINATE does not let you do this.
  1316. # end
  1317.  
  1318.  
  1319. # index "Syntax"
  1320. Syntax:
  1321.  
  1322. # unit
  1323. # verbatim
  1324.     PAGINATE infile outfile [ /Cctlfile ] [ /BEEP | /-BEEP ] [ /DEBUG ]
  1325.       [ /OVERWRITE | /APPEND | /-OVERWRITE | /OVERASK ] [ /Iinitfile | /-I ]
  1326.       [ /marker command ]...
  1327.       [ /? ] [ /?&H ]
  1328. # end
  1329.  
  1330. where:
  1331.  
  1332. # index "Infile parameter"
  1333. "infile" is the input file to process.  This file can contain INCLUDE statements
  1334. to add in other files to process.
  1335.  
  1336. # index "Outfile parameter"
  1337. "outfile" specifies the name of the output file that is to contain the resulting
  1338. text.
  1339.  
  1340. # index "Ctlfile parameter"
  1341. # index "/Cctlfile parameter"
  1342. "/Cctlfile" is basically the same thing as the infile but it typically contains
  1343. only marker commands.  For example, you might have a straight text file
  1344. contained in "infile" and then use the "ctlfile" to say how that text file
  1345. should be processed.
  1346.  
  1347. # index "/BEEP parameter"
  1348. "/BEEP" says to sound a tone when the program is finished executing.
  1349.  
  1350. # index "/-BEEP parameter"
  1351. "/-BEEP" says to not sound a tone when the program finishes.  This is initially
  1352. the default.
  1353.  
  1354. # index "/DEBUG parameter"
  1355. "/DEBUG" is used for debugging purposes.  You might use it when you get an
  1356. error message that doesn't clearly tell you where the error occurred.  /DEBUG
  1357. will show you the text as it's processed and let you see what's actually being
  1358. processed and written.
  1359.  
  1360. # index "/OVERWRITE parameter"
  1361. "/OVERWRITE" says to overwrite the output file if it exists already.
  1362.  
  1363. # index "/-OVERWRITE parameter"
  1364. "/-OVERWRITE" says to abort if the output file exists already.
  1365.  
  1366. # index "/APPEND parameter"
  1367. "/APPEND" says to append (add) to the output file if it exists already.  This
  1368. option is only available if you're creating either a fixed-field or ASCII-
  1369. delimited output file.
  1370.  
  1371. # index "/OVERASK parameter"
  1372. "/OVERASK" says to ask if the output file exists already.  This is initially
  1373. the default.
  1374.  
  1375. # index "/Iinitfile parameter"
  1376. "/Iinitfile" says to read an initialization file with the file name "initfile".
  1377. The file specification *must* contain a period.  If no drive or path information
  1378. is specified, the program will search for initfile beginning in your default
  1379. subdirectory and then going throughout your DOS path.  The use of an
  1380. initialization file is optional.  Initially defaults to "/IPAGINATE.INI".
  1381.  
  1382. # index "/-I parameter"
  1383. # index "/INULL parameter"
  1384. "/-I" (or "/INULL") says to skip loading the initialization file.
  1385.  
  1386. "/marker command" allows you to specify one or more marker commands.  These are
  1387. spelled out in this documentation.
  1388.  
  1389. # index "/? parameter"
  1390. "/?" or "/HELP" or "HELP" shows you the syntax for the command.
  1391.  
  1392. # index "/?&H parameter"
  1393. "/?&H" gives you a hexadecimal and decimal conversion table.
  1394.  
  1395.  
  1396. # index "Guthrie, Bruce"
  1397. # index "Wayne Software"
  1398. Author:
  1399.  
  1400. This program was written by Bruce Guthrie of Wayne Software.  It is free for use
  1401. and redistribution provided relevant documentation is kept with the program, no
  1402. changes are made to the program or documentation, and it is not bundled with
  1403. commercial programs or charged for separately.  People who need to bundle it in
  1404. for-sale packages must pay a $50 registration fee to "Wayne Software" at the
  1405. following address.
  1406.  
  1407. Additional information about this and other Wayne Software programs can be found
  1408. in the file BRUCEymm.DOC which should be included in the original ZIP file.
  1409. ("ymm" is replaced by the last digit of the year and the two digit month of the
  1410. release.  BRUCE412.DOC came out in December 1994.  This same naming convention
  1411. is used in naming the ZIP file that this program was included in.) Comments and
  1412. suggestions can also be sent to:
  1413.  
  1414.  
  1415.                 Bruce Guthrie
  1416.                 Wayne Software
  1417.                 113 Sheffield St.
  1418.                 Silver Spring, MD 20910
  1419.  
  1420.                 fax: (301) 588-8986
  1421.  
  1422. See BRUCEymm.DOC file for additional contact information.
  1423.  
  1424. Foreign users:  Please provide an Internet e-mail address in all correspondence.
  1425.  
  1426.  
  1427. # verbatim
  1428. # index "Decimal codes"
  1429. # index "Hexadecimal codes"
  1430. Decimal and hexadecimal codes:
  1431.   e.g. "\066\097\116" and "&H426174" both are "Bat"
  1432. +---------------------------------------------------------------------------
  1433. | dec  hex chr | dec  hex chr | dec  hex chr | dec  hex chr | dec  hex chr |
  1434. +--------------+--------------+--------------+--------------+--------------+
  1435. | \000 &H00 nul| \052 &H34 4  | \104 &H68 h  | \156 &H9C £  | \208 &HD0 ╨  |
  1436. | \001 &H01   | \053 &H35 5  | \105 &H69 i  | \157 &H9D ¥  | \209 &HD1 ╤  |
  1437. | \002 &H02   | \054 &H36 6  | \106 &H6A j  | \158 &H9E ₧  | \210 &HD2 ╥  |
  1438. | \003 &H03   | \055 &H37 7  | \107 &H6B k  | \159 &H9F ƒ  | \211 &HD3 ╙  |
  1439. | \004 &H04   | \056 &H38 8  | \108 &H6C l  | \160 &HA0 á  | \212 &HD4 ╘  |
  1440. | \005 &H05   | \057 &H39 9  | \109 &H6D m  | \161 &HA1 í  | \213 &HD5 ╒  |
  1441. | \006 &H06   | \058 &H3A :  | \110 &H6E n  | \162 &HA2 ó  | \214 &HD6 ╓  |
  1442. | \007 &H07 bel| \059 &H3B ;  | \111 &H6F o  | \163 &HA3 ú  | \215 &HD7 ╫  |
  1443. | \008 &H08 bs | \060 &H3C <  | \112 &H70 p  | \164 &HA4 ñ  | \216 &HD8 ╪  |
  1444. | \009 &H09 tab| \061 &H3D =  | \113 &H71 q  | \165 &HA5 Ñ  | \217 &HD9 ┘  |
  1445. | \010 &H0A lf | \062 &H3E >  | \114 &H72 r  | \166 &HA6 ª  | \218 &HDA ┌  |
  1446. | \011 &H0B vt | \063 &H3F ?  | \115 &H73 s  | \167 &HA7 º  | \219 &HDB █  |
  1447. | \012 &H0C pg | \064 &H40 @  | \116 &H74 t  | \168 &HA8 ¿  | \220 &HDC ▄  |
  1448. | \013 &H0D cr | \065 &H41 A  | \117 &H75 u  | \169 &HA9 ⌐  | \221 &HDD ▌  |
  1449. | \014 &H0E   | \066 &H42 B  | \118 &H76 v  | \170 &HAA ¬  | \222 &HDE ▐  |
  1450. | \015 &H0F   | \067 &H43 C  | \119 &H77 w  | \171 &HAB ½  | \223 &HDF ▀  |
  1451. | \016 &H10   | \068 &H44 D  | \120 &H78 x  | \172 &HAC ¼  | \224 &HE0 α  |
  1452. | \017 &H11   | \069 &H45 E  | \121 &H79 y  | \173 &HAD ¡  | \225 &HE1 ß  |
  1453. | \018 &H12   | \070 &H46 F  | \122 &H7A z  | \174 &HAE «  | \226 &HE2 Γ  |
  1454. | \019 &H13   | \071 &H47 G  | \123 &H7B {  | \175 &HAF »  | \227 &HE3 π  |
  1455. | \020 &H14   | \072 &H48 H  | \124 &H7C |  | \176 &HB0 ░  | \228 &HE4 Σ  |
  1456. | \021 &H15   | \073 &H49 I  | \125 &H7D }  | \177 &HB1 ▒  | \229 &HE5 σ  |
  1457. | \022 &H16   | \074 &H4A J  | \126 &H7E ~  | \178 &HB2 ▓  | \230 &HE6 µ  |
  1458. | \023 &H17   | \075 &H4B K  | \127 &H7F   | \179 &HB3 │  | \231 &HE7 τ  |
  1459. | \024 &H18   | \076 &H4C L  | \128 &H80 Ç  | \180 &HB4 ┤  | \232 &HE8 Φ  |
  1460. | \025 &H19   | \077 &H4D M  | \129 &H81 ü  | \181 &HB5 ╡  | \233 &HE9 Θ  |
  1461. | \026 &H1A eof| \078 &H4E N  | \130 &H82 é  | \182 &HB6 ╢  | \234 &HEA Ω  |
  1462. | \027 &H1B esc| \079 &H4F O  | \131 &H83 â  | \183 &HB7 ╖  | \235 &HEB δ  |
  1463. | \028 &H1C   | \080 &H50 P  | \132 &H84 ä  | \184 &HB8 ╕  | \236 &HEC ∞  |
  1464. | \029 &H1D ???| \081 &H51 Q  | \133 &H85 à  | \185 &HB9 ╣  | \237 &HED φ  |
  1465. | \030 &H1E ???| \082 &H52 R  | \134 &H86 å  | \186 &HBA ║  | \238 &HEE ε  |
  1466. | \031 &H1F ???| \083 &H53 S  | \135 &H87 ç  | \187 &HBB ╗  | \239 &HEF ∩  |
  1467. | \032 &H20    | \084 &H54 T  | \136 &H88 ê  | \188 &HBC ╝  | \240 &HF0 ≡  |
  1468. | \033 &H21 !  | \085 &H55 U  | \137 &H89 ë  | \189 &HBD ╜  | \241 &HF1 ±  |
  1469. | \034 &H22 "  | \086 &H56 V  | \138 &H8A è  | \190 &HBE ╛  | \242 &HF2 ≥  |
  1470. | \035 &H23 #  | \087 &H57 W  | \139 &H8B ï  | \191 &HBF ┐  | \243 &HF3 ≤  |
  1471. | \036 &H24 $  | \088 &H58 X  | \140 &H8C î  | \192 &HC0 └  | \244 &HF4 ⌠  |
  1472. | \037 &H25 %  | \089 &H59 Y  | \141 &H8D ì  | \193 &HC1 ┴  | \245 &HF5 ⌡  |
  1473. | \038 &H26 &  | \090 &H5A Z  | \142 &H8E Ä  | \194 &HC2 ┬  | \246 &HF6 ÷  |
  1474. | \039 &H27 '  | \091 &H5B [  | \143 &H8F Å  | \195 &HC3 ├  | \247 &HF7 ≈  |
  1475. | \040 &H28 (  | \092 &H5C \  | \144 &H90 É  | \196 &HC4 ─  | \248 &HF8 °  |
  1476. | \041 &H29 )  | \093 &H5D ]  | \145 &H91 æ  | \197 &HC5 ┼  | \249 &HF9 ∙  |
  1477. | \042 &H2A *  | \094 &H5E ^  | \146 &H92 Æ  | \198 &HC6 ╞  | \250 &HFA ·  |
  1478. | \043 &H2B +  | \095 &H5F _  | \147 &H93 ô  | \199 &HC7 ╟  | \251 &HFB √  |
  1479. | \044 &H2C ,  | \096 &H60 `  | \148 &H94 ö  | \200 &HC8 ╚  | \252 &HFC ⁿ  |
  1480. | \045 &H2D -  | \097 &H61 a  | \149 &H95 ò  | \201 &HC9 ╔  | \253 &HFD ²  |
  1481. | \046 &H2E .  | \098 &H62 b  | \150 &H96 û  | \202 &HCA ╩  | \254 &HFE ■  |
  1482. | \047 &H2F /  | \099 &H63 c  | \151 &H97 ù  | \203 &HCB ╦  | \255 &HFF    |
  1483. | \048 &H30 0  | \100 &H64 d  | \152 &H98 ÿ  | \204 &HCC ╠  |              |
  1484. | \049 &H31 1  | \101 &H65 e  | \153 &H99 Ö  | \205 &HCD ═  |              |
  1485. | \050 &H32 2  | \102 &H66 f  | \154 &H9A Ü  | \206 &HCE ╬  |              |
  1486. | \051 &H33 3  | \103 &H67 g  | \155 &H9B ¢  | \207 &HCF ╧  |              |
  1487. +--------------+--------------+--------------+--------------+--------------+
  1488. #
  1489. # unit
  1490. # center
  1491. Index
  1492.  
  1493. # end
  1494. # multicolumn 2
  1495. # include index
  1496. # end
  1497.